<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
		<link rel="stylesheet" type="text/css" href="styles/reset.css"/>
		<link rel="stylesheet" type="text/css" href="sytles/fonts.css"/>
		<link rel="stylesheet" href="styles/screen.css" type="text/css" media="screen, projection"/>
		<link rel="stylesheet" href="styles/print.css" type="text/css" media="print"/>
		<!--[if lt IE 8]>
			<link rel="stylesheet" href="styles/ie.css" type="text/css" media="screen, projection"/>
		<![endif]-->
		
		<link rel="stylesheet" href="styles/plugins/fancy-type/screen.css" type="text/css" media="screen, projection"/>
		<link rel="stylesheet" type="text/css" href="styles/main.css"/>
		<title>phpBoing Documentation</title>
	</head>
	<body>
		<div class="container">
			<div class="span-24">
				<h1>phpBoing Documentation</h1>
			</div>
			<div class="span-6">
				<ul>
					<li><a href="#intro">Introduction</a></li>
					<li><a href="#the_context">The Application Context</a></li>
					<ul>
						<li><a href="#beans">Beans</a></li>
						<li><a href="#properties">Properties</a></li>
					</ul>
					<li><a href="#caching">Caching</a></li>
					<li><a hrf="#example">Examples</a></li>
					<li><a href="#ref_app">Reference Application</a></li>
					<li><a href="#credits">Credits</a></li>
				</ul>
			</div>
			<div class="span-18 last">
				<h3><a name="intro">Introduction</a></h3>
				<p>
					So, what is <code>phpBoing</code> and why did I even bother? 
					<p/>
					Good question. It started out as a school project, well not even a school a project,
					more like a tool to help with a school project. Working on a masters degree in computer
					science, the class was assigned to build a web application. I had grown quite comfortable
					over the years with <a href="http://www.springframework.org" target="_new">the Spring
					Framework</a> and was wanting to use IoC/DI (Inversion of Control/Dependency Injection)
					for this assignment. I looked for a suitable library in PHP (the project had to be written
					in PHP) and found nothing to my liking. Because I hadn't any extra time, I just decided
					to go ahead and "port" Spring in PHP. 
					<p/>
					This system isn't meant to break new ground, but it was meant to give me the functionality
					of a system I already knew inside and out. I wanted the familiarity. It wasn't until I 
					started to use boing on work project that it became clear that some other people might
					find this useful, so here we are. 
				</p>
				<h3><a name="the_context">The Application Context</a></h3>
				<p>
					The application context is a single or series of XML files that define "beans" which 
					constitute the functional pieces of code within your application. Currently <code>boing</code>
					looks at the variable <code>CONTEXT_XML</code> (defined in <code>config.php</code>) to 
					determine which XML file it should load. 
					<p/>
					You may define any number of XML files and simply "include" them into your main (or "master")
					context XML:
					<pre>
&lt;import resource="some-file.xml"/&gt;
					</pre>
					It is within these XML files that you specify "beans" and "properties" which are in turned
					"called" by your code (for a quick look at how this works, look at the <code>example.php</code>
					file.)
					<p/>
					To start, we'll look at a very simple application context XML file, and describe each line
					of code:
<pre>
&lt;?xml version="1.0"?&gt;
&lt;beans&gt;
  &lt;bean id="simple-class" class="org.foo.bar.SimpleClass"&gt;
    &lt;property name="someField"&gt;
      &lt;value>foo is bar&lt;/value&gt;
    &lt;/property&gt;
  &lt;/bean&gt;
&lt;/beans&gt;
</pre>
				As you can see, we don't validate our XML (yet) but Spring's format is followed rather closely. Start out with 
				a typical XML declaration, and then move on to our root node <code>beans</code>. Here we define one or many
				beans using the <code>bean</code> element. The only attribute that is required is the <code>class</code> attribute. 
				<p/>
				The <code>id</code> attribute will be auto-assigned at run time if omitted. Its usually a good idea to provide
				an <code>id</code> attribute simply because this is the attribute you will use to call your bean. There are times
				when it doesn't make sense to have an <code>id</code> such as the case when you inject a bean class as a property
				of another bean. You wouldn't be calling that particular bean directly, and therefore you may safely omit the
				<code>id</code> attribute.
				<p/>
				You will notice the <code>class</code> attribute's value uses a "dotted" notation for classes. How packaging works
				is very similar to that of Java's class path. In fact, you specify a <code>CLASSPATH</code> variable in <code>config.php</code>
				that tells <code>boing</code> where it should look for classes to load when parsing the application context XML. 
				<p/>
				The <code>CLASSPATH</code> defines the "root" of where your classes will be stored, and you are free to use directories
				to create packages for your classes. In the example above you would have a directory structure like:
				<p/>
				<code>CLASSPATH."/org/foo/bar/SimpleClass.php"</code>
				<p/>
				<br/>
				<h4><a name="beans">Beans</a></h4>
				<p/>
				Beans are individual PHP classes that may define a particular function, unit of work, problem set, that represent 
				a single instance in <code>phpBoing's</code> internal registry. A bean is often thought of as a represnetation
				of: <code>$foo = new Foo()</code>
				<p/>
				At the end of the day <code>phpBoing</code> is simply a registry of objects in memory that your application can use
				when the time is right (the "don't call us, we'll call you" concept of IoC) 
				<p/>
				Currently the only two attributes supported for beans are:
				<ul>
					<li><code>id</code> - usable name for this bean</li>
					<li><code>class</code> - the class that defines this bean
				</ul>
				<br/>
				<h4><a name="properties">Properties</a></h4>
				<p/>
				Properties represent fields for a particular bean. We can use properties for settings, "injecting" other beans 
				(as dependencies on the parent beans, where we get the "dependency injection" concept from). Properties can
				provide simple string values, to complex collections or, as stated, other beans. Below illustrates what are
				valid elements for properties:
				
				<table>
					<tr>
						<th>Element</th>
						<th>Example</th>
					</tr>
					<tr>
						<td>
							<code>value</code>
						</td>
						<td>
							<code>&lt;property name="foo"&gt;&lt;value&gt;foo is bar&lt;/value&gt;</code>
						</td>
					</tr>
					<tr>
						<td>
							<code>bean</code>
						</td>
						<td>
<pre>&lt;property name="someObj"&gt;
  &lt;bean class="some.package.beans.FooBar"&gt;
&lt;/property&gt;</pre>
						</td>
					</tr>
					<tr>
						<td>
							<code>list</code>
						</td>
						<td>
<pre>&lt;property name="some_list"&gt;
  &lt;list&gt;
    &lt;value&gt;some value&lt;/value&gt;
    &lt;value&gt;some other value&lt;/value&gt;
  &lt;/list&gt;
&lt;/property&gt;</pre>
						</td>
					</tr>
					<tr>
						<td>
							<code>map</code>
						</td>
						<td>
<pre>&lt;property name="some_map"&gt;
  &lt;map&gt;
    &lt;entry key="name_of_key"&gt;&lt;value&gt;value for this key&lt;/value&gt;&lt;/entry&gt;
    &lt;entry key="another_key"&gt;&lt;value&gt;another value&lt;/value&gt;&lt;/entry&gt;
  &lt;/map&gt;
&lt;/property&gt;</pre>						
						</td>
					</tr>
				</table>
				It should be noted that for <code>map</code> and <code>list</code> you can use complex values
				(of nested <code>map</code>s, <code>list</code>s and/or <code>bean</code>s)
				<p/>
				In addition to hard-coding simple (string) values, you can also use the special bean: <code>PropertyPlaceholderConfigurer</code>
				which enables you to use a separate properties/configuration file using key/values pairs for your string values. An example:
<pre>
&lt;bean 
  class="org.phpbboing.util.PropertyPlaceholderConfigurer"&gt;
    &lt;property name="locations"&gt;
      &lt;list&gt;
        &lt;value&gt;../configs/foo.properties&lt;/value&gt;
      &lt;/list&gt;
    &lt;/property&gt;
&lt;/bean&gt;
</pre>
					This class currently resides in the <code>ref_app</code> file system. 
					<p/>
					Basically this works (just as the Spring Property Placeholder Configurer) by providing a list
					of properties files to the configurer and then parses them (using PHP's <code>parse_ini</code> function)
					and provides the container with a symbol table of all key/value pairs it found. 
					<p/>
					To use your configuration variables within an application context XML, simply use the syntax:
					<p/>
					<code>${key}</code>
					<p/>
					Below is an example:
					
<pre>
----- props snippet ------
my.key = a simple value
----- end props snippet --
</pre>
<pre>
&lt;bean id="my-bean" class="org.some.package.FooBar"&gt;
  &lt;property name="my_prop"&gt;
    &lt;value&gt;${my.key}&lt;/value&gt;
  &lt;/property&gt;
&lt;/bean&gt;
</pre>
				<h3><a name="caching">Caching</a></h3>
				<p/>
				Because PHP has no notion of "static" variables, variables that live outside and beyond that of the
				web application, there is a mechanism in place that persists our application context registry. This is
				done primarily because of performance. 
				<p/>
				It would be a very bad idea for every click to parse one or many application context XML files, which is
				exactly what would happen if there wasn't a caching mechanism built into <code>phpBoing</code>.
				<p/>
				The currently caching mechanism is that of <a href="http://www.danga.com/memcached/" target="_new">Memcached</a>
				a very simple, powerful and lightweight memory caching system. You will need to have Memcached installed and
				running on your machine where  you intend to use <code>phpBoing</code>. 
				<p/>
				How this works is, located in the <code>phpBoing</code> distribution is the <code>c_tools.php</code> file which
				defines a <code>Tools</code> class. This class contains several static functions that the container uses, one
				series of functions are the add to, delete from and get functions for memcached. The container,  once instantiated
				(in your code) will look to see if there's a cached version of the <code>BEAN_CONTAINER</code> (which is the
				internal registry of all beans). If one does not exist, we then parse our XML file(s) then we take the resulting
				registry and copy it to memcached. 
				</p>
				<br/>
				<h3><a name="examples">Examples</a></h3>
				<p/>
				As part of the distribution of <code>phpBoing</code>  you will notice a simple example: <code>example.php</code>
				this brief example will illustrate how each of the pieces of <code>phpBoing</code> fit together and how you
				can use it in your application. The nice thing is that using <code>boing</code> means you do not have to 
				re-engineer your application. You can use it as much or as little as you want, <code>boing</code> makes no
				assumptions about your application, how you built or what it does. 
				<p/>
				As part of the <code>example.php</code> there is also a very simple class path that makes up this example located
				in: <code>classes</code>.
				<p/>
				<br/>
				<h3><a name="ref_app">Reference Application</a></h3>
				<p/>
				The reference application is a full fledged MVC (Model-View-Controller) framework that attempts to show how a real
				world application might use <code>phpBoing</code>. You can use the <code>make-site.php</code> command-line
				script to create a web site shell for you, using your settings defined in <code>my_site.ini</code>
				<p/>
				To create a site, simply create a site INI file (you can use the <code>my_site.ini</code> as a template) then
				execute <code>make-site.php</code> on the command line:
				<p/>
				<code>./make-site.php my_site.ini</code>
				<p/>
				This will create the entire file structure for your site. 
				<p/>
				Again, <code>phpBoing</code> is NOT a web application framework. This reference application is only included
				as a way to show a real world system (which is actually derived from several actual projects). 
				<p/>
				This reference application will most likely NOT be maintained in that is not the goal of this project, and may at
				some point in the future be dropped from the distribution all together. 
				<p/>
				<br/>
				<h3><a name="credits">Credits</a></h3>
				<p/>
				<ul>
					<li>Originating author and chief maintainer: david palmer <code>blinder (dot) dave (at) gmail (dot) com</code></li>
					<li>Main contributor: craig andrews <code>candrews (at) integralblue (dot) com</code>
				</ul>
				Thanks go out to: the whole Spring Framework community, for making a really nice container. 
				</p>
				<br/><br/><br/>
				<hr/>
				<em>content is available under Creative Commons Attribution 2.5</em> ||||| 
				<code>phpBoing</code> available through <a href="http://www.apache.org/licenses/LICENSE-2.0" target="_new">Apache 2 license</a>
			</div>
		</div>
	</body>
</html>